zx

What is zx?

The zx package is a tool for writing better scripts in a Node.js environment. It provides a more convenient and modern way to write shell scripts using JavaScript, leveraging the power of Node.js and its ecosystem.

What are zx's main functionalities?

Running Shell Commands

This feature allows you to run shell commands directly from your JavaScript code using template literals. The `$` function is used to execute the command and handle the output.

const { $ } = require('zx');

(async () => {
  await $`echo Hello, world!`;
})();

Handling Promises

zx makes it easy to handle promises and errors when running shell commands. You can use async/await syntax to manage asynchronous operations and catch errors using try/catch blocks.

const { $ } = require('zx');

(async () => {
  try {
    await $`exit 1`;
  } catch (error) {
    console.error('Command failed:', error);
  }
})();

Using Environment Variables

You can set and use environment variables within your scripts. This is useful for configuring your script's behavior based on different environments or settings.

const { $ } = require('zx');

(async () => {
  process.env.MY_VAR = 'Hello, world!';
  await $`echo $MY_VAR`;
})();

File System Operations

zx provides convenient access to Node.js's fs module, allowing you to perform file system operations like reading and writing files with ease.

const { fs } = require('zx');

(async () => {
  await fs.writeFile('example.txt', 'Hello, world!');
  const content = await fs.readFile('example.txt', 'utf8');
  console.log(content);
})();

Other packages similar to zx

shelljs

ShellJS is a portable (Windows/Linux/macOS) implementation of Unix shell commands on top of the Node.js API. It provides a similar functionality to zx but uses a more traditional approach with a focus on compatibility with Unix shell commands.

execa

Execa is a modern process execution library for Node.js. It provides a more powerful and flexible way to run shell commands compared to zx, with features like better error handling, streaming, and more detailed output.

child_process

The child_process module is a built-in Node.js module that provides the ability to spawn child processes. While it is more low-level and less convenient than zx, it offers more control and flexibility for advanced use cases.

README

🐚 zx

#!/usr/bin/env zx

await $`cat package.json | grep name`

let branch = await $`git branch --show-current`
await $`dep deploy --branch=${branch}`

await Promise.all([
  $`sleep 1; echo 1`,
  $`sleep 2; echo 2`,
  $`sleep 3; echo 3`,
])

let name = 'foo bar'
await $`mkdir /tmp/${name}`

Bash is great, but when it comes to writing more complex scripts, many people prefer a more convenient programming language. JavaScript is a perfect choice, but the Node.js standard library requires additional hassle before using. The zx package provides useful wrappers around child_process, escapes arguments and gives sensible defaults.

Install

npm i -g zx

Requirement: Node version >= 16.0.0

Goods

$ · cd() · fetch() · question() · sleep() · echo() · stdin() · within() · retry() · spinner() · chalk · fs · os · path · glob · yaml · minimist · which · __filename · __dirname · require()

For running commands on remote hosts, see webpod.

Documentation

Write your scripts in a file with an .mjs extension in order to use await at the top level. If you prefer the .js extension, wrap your scripts in something like void async function () {...}().

Add the following shebang to the beginning of your zx scripts:

#!/usr/bin/env zx

Now you will be able to run your script like so:

chmod +x ./script.mjs
./script.mjs

Or via the zx executable:

zx ./script.mjs

All functions ($, cd, fetch, etc) are available straight away without any imports.

Or import globals explicitly (for better autocomplete in VS Code).

import 'zx/globals'

$`command`

Executes a given command using the spawn func and returns ProcessPromise.

Everything passed through ${...} will be automatically escaped and quoted.

let name = 'foo & bar'
await $`mkdir ${name}`

There is no need to add extra quotes. Read more about it in quotes.

You can pass an array of arguments if needed:

let flags = [
  '--oneline',
  '--decorate',
  '--color',
]
await $`git log ${flags}`

If the executed program returns a non-zero exit code, ProcessOutput will be thrown.

try {
  await $`exit 1`
} catch (p) {
  console.log(`Exit code: ${p.exitCode}`)
  console.log(`Error: ${p.stderr}`)
}

ProcessPromise

class ProcessPromise extends Promise<ProcessOutput> {
  stdin: Writable
  stdout: Readable
  stderr: Readable
  exitCode: Promise<number>

  pipe(dest): ProcessPromise

  kill(): Promise<void>

  nothrow(): this

  quiet(): this
}

Read more about the ProcessPromise.

ProcessOutput

class ProcessOutput {
  readonly stdout: string
  readonly stderr: string
  readonly signal: string
  readonly exitCode: number

  toString(): string // Combined stdout & stderr.
}

The output of the process is captured as-is. Usually, programs print a new line \n at the end. If ProcessOutput is used as an argument to some other $ process, zx will use stdout and trim the new line.

let date = await $`date`
await $`echo Current date is ${date}.`

Functions

cd()

Changes the current working directory.

cd('/tmp')
await $`pwd` // => /tmp

Like echo, in addition to string arguments, cd accepts and trims trailing newlines from ProcessOutput enabling common idioms like:

cd(await $`mktemp -d`)

fetch()

A wrapper around the node-fetch package.

let resp = await fetch('https://medv.io')

question()

A wrapper around the readline package.

let bear = await question('What kind of bear is best? ')

sleep()

A wrapper around the setTimeout function.

await sleep(1000)

echo()

A console.log() alternative which can take ProcessOutput.

let branch = await $`git branch --show-current`

echo`Current branch is ${branch}.`
// or
echo('Current branch is', branch)

stdin()

Returns the stdin as a string.

let content = JSON.parse(await stdin())

within()

Creates a new async context.

await $`pwd` // => /home/path

within(async () => {
  cd('/tmp')

  setTimeout(async () => {
    await $`pwd` // => /tmp
  }, 1000)
})

await $`pwd` // => /home/path

await $`node --version` // => v20.2.0

let version = await within(async () => {
  $.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; nvm use 16;'
  
  return $`node --version`
})

echo(version) // => v16.20.0

retry()

Retries a callback for a few times. Will return after the first successful attempt, or will throw after specifies attempts count.

let p = await retry(10, () => $`curl https://medv.io`)

// With a specified delay between attempts.
let p = await retry(20, '1s', () => $`curl https://medv.io`)

// With an exponential backoff.
let p = await retry(30, expBackoff(), () => $`curl https://medv.io`)

spinner()

Starts a simple CLI spinner.

await spinner(() => $`long-running command`)

// With a message.
await spinner('working...', () => $`sleep 99`)

Packages

The following packages are available without importing inside scripts.

chalk package

The chalk package.

console.log(chalk.blue('Hello world!'))

fs package

The fs-extra package.

let {version} = await fs.readJson('./package.json')

os package

The os package.

await $`cd ${os.homedir()} && mkdir example`

path package

The path package.

await $`mkdir ${path.join(basedir, 'output')}`

globby package

The globby package.

let packages = await glob(['package.json', 'packages/*/package.json'])

yaml package

The yaml package.

console.log(YAML.parse('foo: bar').foo)

minimist package

The minimist package available as global const argv.

if (argv.someFlag) {
  echo('yes')
}

which package

The which package.

let node = await which('node')

Configuration

$.shell

Specifies what shell is used. Default is which bash.

$.shell = '/usr/bin/bash'

Or use a CLI argument: --shell=/bin/bash

$.spawn

Specifies a spawn api. Defaults to require('child_process').spawn.

$.prefix

Specifies the command that will be prefixed to all commands run.

Default is set -euo pipefail;.

Or use a CLI argument: --prefix='set -e;'

$.quote

Specifies a function for escaping special characters during command substitution.

$.verbose

Specifies verbosity. Default is true.

In verbose mode, zx prints all executed commands alongside with their outputs.

Or use the CLI argument --quiet to set $.verbose = false.

$.env

Specifies an environment variables map.

Defaults to process.env.

$.cwd

Specifies a current working directory of all processes created with the $.

The cd() func changes only process.cwd() and if no $.cwd specified, all $ processes use process.cwd() by default (same as spawn behavior).

$.log

Specifies a logging function.

import { LogEntry, log } from 'zx/core'

$.log = (entry: LogEntry) => {
  switch (entry.kind) {
    case 'cmd':
      // for example, apply custom data masker for cmd printing
      process.stderr.write(masker(entry.cmd))
      break
    default:
      log(entry)
  }
}

Polyfills

__filename & __dirname

In ESM modules, Node.js does not provide __filename and __dirname globals. As such globals are really handy in scripts, zx provides these for use in .mjs files (when using the zx executable).

require()

In ESM modules, the require() function is not defined. The zx provides require() function, so it can be used with imports in .mjs files (when using zx executable).

let {version} = require('./package.json')

FAQ

Passing env variables

process.env.FOO = 'bar'
await $`echo $FOO`

Passing array of values

When passing an array of values as an argument to $, items of the array will be escaped individually and concatenated via space.

Example:

let files = [...]
await $`tar cz ${files}`

Importing into other scripts

It is possible to make use of $ and other functions via explicit imports:

#!/usr/bin/env node
import { $ } from 'zx'

await $`date`

Scripts without extensions

If script does not have a file extension (like .git/hooks/pre-commit), zx assumes that it is an ESM module.

Markdown scripts

The zx can execute scripts written as markdown:

zx docs/markdown.md

TypeScript scripts

import { $ } from 'zx'
// Or
import 'zx/globals'

void async function () {
  await $`ls -la`
}()

Set "type": "module" in package.json and "module": "ESNext" in tsconfig.json.

Executing remote scripts

If the argument to the zx executable starts with https://, the file will be downloaded and executed.

zx https://medv.io/game-of-life.js

Executing scripts from stdin

The zx supports executing scripts from stdin.

zx << 'EOF'
await $`pwd`
EOF

Executing scripts via --eval

Evaluate the following argument as a script.

cat package.json | zx --eval 'let v = JSON.parse(await stdin()).version; echo(v)'

Installing dependencies via --install

// script.mjs:
import sh from 'tinysh'

sh.say('Hello, world!')

Add --install flag to the zx command to install missing dependencies automatically.

zx --install script.mjs

You can also specify needed version by adding comment with @ after the import.

import sh from 'tinysh' // @^1

Executing commands on remote hosts

The zx uses webpod to execute commands on remote hosts.

import { ssh } from 'zx'

await ssh('user@host')`echo Hello, world!`

Attaching a profile

By default child_process does not include aliases and bash functions. But you are still able to do it by hand. Just attach necessary directives to the $.prefix.

$.prefix += 'export NVM_DIR=$HOME/.nvm; source $NVM_DIR/nvm.sh; '
await $`nvm -v`

Using GitHub Actions

The default GitHub Action runner comes with npx installed.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build
        env:
          FORCE_COLOR: 3
        run: |
          npx zx <<'EOF'
          await $`...`
          EOF

Canary / Beta / RC builds

Impatient early adopters can try the experimental zx versions. But keep in mind: these builds are ⚠️️__beta__ in every sense.

npm i zx@dev
npx zx@dev --install --quiet <<< 'import _ from "lodash" /* 4.17.15 */; console.log(_.VERSION)'

License

Apache-2.0

Disclaimer: This is not an officially supported Google product.